Fix unhandled JSON parse error on non-JSON HTTP responses with MCP-compliant error handling by Copilot · Pull Request #18 · PaystackOSS/paystack-mcp-server

Copilot · 2026-02-20T23:44:37Z

The makeRequest function throws unhandled exceptions when API gateways return HTML error pages (502, 504, etc.) instead of JSON, causing server crashes. This PR implements graceful error handling at both the HTTP client and tool layers, following Model Context Protocol (MCP) best practices.

Changes

Enhanced error handling in paystack-client.ts:
- Capture HTTP status code from response object
- Truncate long responses to 200 chars in error message, preserve full text in error object
- Replace generic "Invalid JSON response" with context-rich error message
MCP-compliant tool error handling in src/tools/:
- Added isError: true flag to tool responses on failures (per MCP specification)
- Enhanced error messages to include HTTP status codes when available
- Updated both make-paystack-request and get-paystack-operation tools
Added comprehensive test coverage:
- Client layer tests in test/paystack-client.spec.ts: Non-JSON responses, truncation behavior, valid JSON parsing
- Tool layer tests in test/make-paystack-request-tool.spec.ts: isError flag behavior, status codes, network errors
- Total: 9 tests covering both layers

Example

HTTP Client Error (Before):

Error: Invalid JSON response: <html><body><h1>502 Bad Gateway</h1>...

HTTP Client Error (After):

Error: Received non-JSON response from server (HTTP 502): <html><body><h1>502 Bad Gateway</h1>...

Tool Response (MCP-Compliant):

{
  "content": [{
    "type": "text",
    "text": "Unable to make request (HTTP 502): Received non-JSON response from server..."
  }],
  "isError": true
}

The error object now includes statusCode and responseText properties for debugging. Tool responses follow MCP best practices, allowing LLMs to properly identify and handle execution failures.

cc @tolu-paystack

Original prompt

This section details on the original issue you should resolve

<issue_title>[Bug]: makeRequest throws unhandled JSON.parse syntax error on non-JSON HTTP responses</issue_title>
<issue_description>### What happened?

The code fails to handle standard HTTP edge cases. If an API gateway returns an HTML error page (like a 502 Bad Gateway), the server crashes due to an unhandled exception.

Version

1.0.2 (Default)

Relevant log output
Code of Conduct

I agree to follow the project's Code of Conduct</issue_description>

<agent_instructions>add a graceful failure response when the server returns a non JSON response. Tag me in the p/r for review.</agent_instructions>

Comments on the Issue (you are @copilot in this section)
@tolu-paystack Thanks for reporting this @OwenMaine! We'll take a look and share feedback here

Fixes [Bug]: makeRequest throws unhandled JSON.parse syntax error on non-JSON HTTP responses #13

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

- Enhanced error message to include HTTP status code - Truncate long responses to 200 characters for readability - Attach statusCode and full responseText to error object for debugging - Added comprehensive test suite for non-JSON response handling Co-authored-by: Andrew-Paystack <78197464+Andrew-Paystack@users.noreply.github.com>

Andrew-Paystack

This change focused on the http client but didn't follow the recommended structure for tools returning errors.

Check the docs here

- Updated make-paystack-request tool to return isError: true on failures - Updated get-paystack-operation tool to return isError: true on failures - Enhanced error messages to include HTTP status codes - Added comprehensive test suite for tool-level error handling - All 9 tests passing (4 new tool tests + 5 existing client tests) Co-authored-by: Andrew-Paystack <78197464+Andrew-Paystack@users.noreply.github.com>

- Use more specific error message: 'Error retrieving operation' vs 'Unable to retrieve operation' - Fix test name to accurately reflect what is being tested Co-authored-by: Andrew-Paystack <78197464+Andrew-Paystack@users.noreply.github.com>

Copilot · 2026-02-23T17:05:42Z

This change focused on the http client but didn't follow the recommended structure for tools returning errors.

Check [the docs here](https://modelcontextprotocol.info/docs/concepts/tools/#error-hand...

Updated to follow MCP best practices. Tools now return isError: true flag on failures per the MCP specification. Changes in commit f0af09a.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

modelcontextprotocol.info
- Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Initial plan

201eb0a

Copilot AI assigned Copilot and Andrew-Paystack Feb 20, 2026

Copilot started work on behalf of Andrew-Paystack February 20, 2026 23:44 View session

Copilot AI changed the title ~~[WIP] Add graceful failure response for non-JSON HTTP responses~~ Fix unhandled JSON parse error on non-JSON HTTP responses Feb 20, 2026

Copilot AI requested a review from Andrew-Paystack February 20, 2026 23:51

Copilot finished work on behalf of Andrew-Paystack February 20, 2026 23:51

Andrew-Paystack approved these changes Feb 23, 2026

View reviewed changes

Andrew-Paystack requested changes Feb 23, 2026

View reviewed changes

Copilot started work on behalf of Andrew-Paystack February 23, 2026 16:59 View session

Copilot AI and others added 2 commits February 23, 2026 17:03

Address code review feedback

f0af09a

- Use more specific error message: 'Error retrieving operation' vs 'Unable to retrieve operation' - Fix test name to accurately reflect what is being tested Co-authored-by: Andrew-Paystack <78197464+Andrew-Paystack@users.noreply.github.com>

Copilot AI changed the title ~~Fix unhandled JSON parse error on non-JSON HTTP responses~~ Fix unhandled JSON parse error on non-JSON HTTP responses with MCP-compliant error handling Feb 23, 2026

Copilot AI requested a review from Andrew-Paystack February 23, 2026 17:06

Copilot finished work on behalf of Andrew-Paystack February 23, 2026 17:06

Andrew-Paystack marked this pull request as ready for review February 23, 2026 17:14

Andrew-Paystack requested a review from a team February 23, 2026 17:14

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

Fix unhandled JSON parse error on non-JSON HTTP responses with MCP-compliant error handling#18

Fix unhandled JSON parse error on non-JSON HTTP responses with MCP-compliant error handling#18
Copilot wants to merge 4 commits intomainfrom
copilot/add-graceful-failure-response

Copilot AI commented Feb 20, 2026 •

edited

Loading

Uh oh!

Andrew-Paystack left a comment

Uh oh!

Copilot AI commented Feb 23, 2026 •

edited

Loading

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

Conversation

Copilot AI commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Example

Version

Relevant log output

Code of Conduct

Comments on the Issue (you are @copilot in this section)

Uh oh!

Andrew-Paystack left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Feb 20, 2026 •

edited

Loading

Copilot AI commented Feb 23, 2026 •

edited

Loading